home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / syslog.arc / SYSLOG.DOC < prev    next >
Text File  |  1990-03-26  |  7KB  |  197 lines
  1.  
  2.                      SYSLOG
  3.  
  4.              Copyright (C) Wes Cowley 1990
  5.                   All rights reserved
  6.  
  7. Purpose
  8. -------
  9.  
  10. One feature of mainframe computers that I miss in the microcomputer world is
  11. a system log.  On the monster mainframes I've worked on every event that is
  12. potentially interesting is logged.  This provides a central location for 
  13. status messages and error messages.  Until recently, micros didn't really
  14. need something like this because they were running one program at a time, 
  15. usually with the operator right there watching the screen.  Even if the 
  16. program wasn't being watching when something went wrong the number of error 
  17. logs that needed to be checked was minimized by fact that the user usually
  18. knew what was running.  With the growing number of micro systems running 
  19. multitasking software the need for such a log facility is becoming greater.
  20.  
  21. SysLog provides this feature for the DESQview environment.  When run, SysLog
  22. opens a window and waits for other programs to send log messages to it.  When
  23. a message is received, it is displayed to the window along with a timestamp.
  24. There is an option to maintain a log file containing all incoming messages.
  25. Messages sent to SysLog can be marked as being urgent.  When an urgent message
  26. is received SysLog will highlight the message and move its window to the top
  27. of DESQview's window stack.
  28.  
  29. Usage
  30. -----
  31.  
  32. SysLog comes with a .DVP file which contains the setup used on my system.  
  33. The Parameters line should be modified to match your needs.  Case is not
  34. significant in specifying parameters.  The parameters currently recognized 
  35. by Syslog are:
  36.  
  37.     /F<file name>
  38.  
  39.         Specify the name of the log file that SysLog will maintain.
  40.         SysLog will append every message received to this file.  The
  41.         default action if this parameter is not specified is to not 
  42.         maintain a log file.  
  43.  
  44.     /M<mailbox name>
  45.  
  46.         Specify the name of the mailbox that SysLog will open.  
  47.         This allows multiple copies of SysLog to be running, each 
  48.         receiving log messages from different sources.  The default
  49.         mailbox name is SysLog.
  50.  
  51.     /T<n>
  52.         Specify the number of seconds SysLog will wait after 
  53.         receiving a message before committing the log file to 
  54.         disk.  When the file is committed no messages which have
  55.         been previously received will be lost in the event of a
  56.         system crash.  The default is to wait 10 seconds.  If /T0 
  57.         is used, there will be almost no delay before committing
  58.         the file.  
  59.  
  60. The command line I currently use is: 
  61.  
  62.     /Fc:\dv\utils\syslog.log /T30
  63.  
  64. Program Interface
  65. -----------------
  66.  
  67. Messages may be sent to SysLog in one of two ways, through either the 
  68. Log utility or SysLog's API.  The Log utility is the easiest method of
  69. getting messages into the system log.  It is most useful when run either
  70. from a batch file or from an application script.  The syntax is as follows:
  71.  
  72.     Log [<flags>] <message>
  73.  
  74. The flags recognized by Log are:
  75.  
  76.     /M<mailbox name>
  77.     
  78.         Specifies the name of the mailbox that SysLog is using.  See
  79.         the corresponding parameter to SysLog for more information.
  80.         The default mailbox name is SysLog.
  81.  
  82.     /U
  83.  
  84.         Specifies that the message is urgent.  
  85.  
  86. For example:
  87.  
  88.     Log "OOPS! Download was unsuccessful."
  89.  
  90.  
  91. The other method of putting messages into the log requires that the sending
  92. program be SysLog specific as well as DESQview specific.  SysLog supports
  93. a small applications program interface (API) through which a program
  94. can communicate with SysLog. 
  95.  
  96. The first step in using the SysLog API is to find it's mailbox.  DESQview's 
  97. FINDMAIL command should be used to find the handle of SysLog's mailbox.  
  98. Unless the name has been changed with the /M parameter the mailbox name will 
  99. be SysLog.  Once your program has the mailbox handle it can communicate with 
  100. SysLog.  There are currently three commands supported by the SysLog: Link, 
  101. Unlink, and Message.     The formats of these commands are as follows:
  102.  
  103.     Format of Link message 
  104.     ----------------------
  105.  
  106.     Total length: n bytes
  107.  
  108.     Ofs    Length    Description
  109.     ---    ------    -----------
  110.        0      1    Message type == 0 (SL_LINK)
  111.        1      1     Control flags
  112.      2          n-2    Program name (maximum length: 40 bytes)
  113.  
  114.  
  115.       Control flags:
  116.  
  117.         Bit 0: 0 == announce link (default)
  118.                1 == do not announce link (SL_LINK_QUIET)
  119.            Bits 1 - 7: reserved 
  120.  
  121.  
  122.      Format of Unlink message 
  123.     ------------------------
  124.  
  125.     Total length: n bytes
  126.  
  127.     Ofs    Length    Description
  128.     ---    ------    -----------
  129.        0       1    Message type == 1 (SL_UNLINK)
  130.        1       1    Control flags
  131.        2      n-2    Program name (maximum length: 40 bytes)
  132.  
  133.       Control flags:
  134.  
  135.         Bit 0: 0 == announce unlink (default)
  136.                1 == do not announce unlink (SL_UNLINK_QUIET)
  137.          Bits 1 - 7: reserved 
  138.  
  139.  
  140.     Format of Msg message 
  141.     ---------------------
  142.  
  143.      Total length: n bytes
  144.  
  145.     Ofs    Length    Description
  146.     ---    ------    -----------
  147.        0      1    Message type == 2 (SL_MSG)
  148.        1      1    Control flags
  149.        2     n-2    Message (maximum length 256 bytes)
  150.  
  151.   Control flags:
  152.  
  153.         Bit 0: 0 == normal message (default)
  154.                1 == urgent message (SL_MSG_URGENT)
  155.            Bits 1 - 7: reserved 
  156.  
  157.  
  158. The Link and Unlink messages are used to inform SysLog that your program will
  159. be using the log file for an extended period of time.  SysLog will prevent 
  160. the user from closing the log window with anything short of a three finger 
  161. salute.  The reason for using these commands is to protect your program from 
  162. the crash that would occur if SysLog's mailbox were to disappear while it was 
  163. being used. SysLog does not maintain a record of which programs linked to it, 
  164. other than displaying a log message if the SL_LINK_QUIET and SL_UNLINK_QUIET
  165. options are not used.  A count of linked programs is maintained.  As long as
  166. the count is greater than zero the user may not close the SysLog window.
  167.  
  168. The Msg command is used to send a log message to SysLog.  It may be used
  169. regardless of whether or not your program has linked to SysLog with the
  170. Link command.  The message will be displayed in the SysLog window and 
  171. recorded in the log file if it is open.  
  172.  
  173.  
  174.  
  175. Distribution
  176. ------------
  177.  
  178. SysLog may be freely copied and distributed as long as no charge is made for 
  179. it other than normal online access charges.
  180.  
  181. Support
  182. -------
  183.  
  184. I will try to provide any needed support through Bix.  If you have problems, 
  185. suggestions, or complaints about this program don't hesitate to send them to 
  186. me there.  Time permitting, I will try to act on them.  I make no promises 
  187. that this program will work with any given hardware or software configuration
  188. or that I will be able fix any problems you find using the program.  This is 
  189. a free program written in my free time.
  190.  
  191.  
  192.  
  193. Wes Cowley (Bix: wcowley)
  194. PO Box 280138
  195. Tampa, FL 33682
  196.  
  197.